Tandy Vendor Development Internal Document Number: VDS-2639Q1-Q1 Microsoft Works Utility Disk August 7, i?ec- Dear Tandy 600 Software Developer; Here Is the Microsc+t wcr < s Ut : iity Disk and documentation yet have requested. Microsoft Work affords the software developer t^e ability to develop) maintain» and debug individual asse-io : y language oragrans a r alternate ROMs from an MS-DCS based CO mou t e r . In order- to use Mfcrcsaft Uarks* the fol lowing is required 1 - Microsoft Macro-Assembler (MASM) version 4.0. - v S-D0S based computer with S12K RAM (not compatible with Tandy 20D0) . Neither Tandy Corporation nor Microsoft wil! offer any support for Microsoft U'arks. Tandy Corporation provides vendor— level technical suoport to those vendors involved in developing products for the Tandv I i ne. If your company is not a member already) please write to the following -for more information: Vendor- Development Services 13D0 One T andy Cente- r ort U-orthj T X 7&1D2 Enc I osures Tandy Vendor Development Internal Document 3 age 1 Microsoft 11 Works™ Debugging Application Programs January 3, 1986 Debugging Works™ programs requires an IBM PC or compatible with 512KB of memory. The Works M environment is run on top of a BIOS simulator which emulates most of the I/O capabilities of a battery-powered portable computer. The language and debugging utilities (which are part of the Microsoft Macro Assembler package) required for developing and debugging Works applications are: -An assembler (MASM) or compiler that is compatible with the Microsoft Linker. -Microsoft** Linker (LINK). -Microsoft 11 Symbolic Debug Utility (SYMDEB). -The MAPSYM utility which translates .MAP files (output by LINK) into .SYM files (read by SYMDEB). The Works™ Development Utilities package includes: -A utility (EXECNV) that converts .EXE files to Works™ executables. -Microsoft* Works™ Rom Generation Program (BLDROM) that builds a ROM image from a specified list of MS-DOS files. -A sample .GEN file (DEBUG.GEN) which contains a list of files that should be built into debugging ROM images. DEBUG.GEN is passed as a command line argument to BLDROM. -works* system files (they have a .SYS extension) that must be built into debugging ROM images. Note that the first file in a debugging ROM image must be the operating system (SSSYS001.SYS). -Two application files, WORD and CALC. -A batch file (MAKEDBG.BAT) that executes BLDROM and deletes any old RAM image files. -An MS-DOS-based BIOS simulator (HHSIM) and associated parameter file (DEBUG.PRM) on top of which a Works™ ROM image can be executed. -Symbol table files (HHSIM.SYM, HHOS.SYM) containing the symbols necessary for stepping through the simulator and operating system in order to reach the entry point of an application. -A batch file (HHDEBUG.BAT) that brings up HHSIM under SYMDEB. The following steps should be followed in order to debug a Works ' application after a ROM image has been built: Enter the following DOS command: HHDEBUG app_symbol_tablc_fiIenamc Enter the following SYMDEB commands: G START D ROMADR L2 SYMDEB output will be of the form. 'seg:off xx yy'. XO HHOS! Z OSCODE yyxx G OSCODE:EXEC T XO HHOS! G OSCODE:EXEC After the System Manager comes up. RUN the application that is to be debugged. T XO app_symbol table filename! Proceed with debugging the application. Microsoft Works™ BLDROM and EXECNV Development Utilities January 3, 1986 Command Line Arguments The BLDROM.EXE utility will construct a ROM image that can be made part of a Works™ ROM file system. The utility takes two command line arguments as follows: BLDROM FENERATION FILENAME> <OUTPUT FILENAME> The generation file, explained in more detail below, contains a list of the MS- DOS files that the ROM image should be constructed from. The name of the generation file must be fully specified; there is no default extension. The output filename is an optional argument. It can be used to specify the file that the resultant ROM image should be written to. The ROM image will be written to "HHC.ROM" if no output file is specified. If a filename without an extension is specified, then "ROM" will be used as the default extension. Generation File In the generation file, there must be one line per file that is to be put in the ROM image. A line in the generation file must have the following format: <MS-DOS™ FILENAME> <WORKS™ FILENAME> The MS-DOS* 4 file is the one containing the bytes which have to be put in a ROM file. Note that it doesn't matter what the semantics of the bytes are - the file could contain either code for an application or arbitrary data. The Works filename indicates what name the file within the ROM image should have. Both filenames must be specified in their entirety; there are no default extensions. ROM Applications Once an application has been written and structured as described in the Microsoft* Works Operating System Programmers' Reference Guide, it should be assembled or compiled into an MS-DOS™ M .EXE" file. This file can appear as the MS-DOS™ filename on a line in the generation file. BLDROM will automatically strip off the ".EXE" header to create a Works executable file. The Works executable file will be named according to the second filename on the line in the generation file. RAM Applications: Use EXECNV In the event that an application is to be stored on disk and run in RAM, the EXECNV utility should be used by itself (BLDROM doesn't get used at all) to perform the ".EXE" conversion. EXECNV takes a ".EXE" file as its only argument (leave out the ".EXE" because it is assumed) and produces a H .HHX' file. The ".HHX" file is ready to be run in a Works environment. ROM Image Structure A ROM image containing n files will have the following structure: 32 byte ROM image header 32 byte file header ROM file #1 32 byte file header ROM file #n 32 byte ROM image terminator Remember to allow for header and terminator overhead when trying to anticipate whether or not a ROM image will fit in a ROM memory region Microsof t R Works™ HHSIM Development Utility January 3, 1986 The HHSIM utility simulates a Works™ environment under MS-DOS™ on an IBM PC. The utility emulates a Works™ BIOS as if the IBM PC were a battery-powered portable computer. The simulator is invoked with the MS-DOS™ command 'HHSIM parameter filename'. If a parameter file is not specified, then HHC.PRM is assumed. If HHC.PRM is not found, then built-in defaults will be used. In the parameter file there must be exactly one parameter per line; blank lines are not allowed. The following are the currently recognized parameters along with their default values: RAMSIZ = 128 RAMFILL = hex_byte_value TXTLIN - 25 TXTCOL = 80 SAVE - filename ROM = HHCROM : size of RAM in K bytes. : default is not to fill. : no. of display lines to use. : no. of display columns to use, : default is not to save. : name of ROM image file. The RAMSIZ parameter specifies the amount of PC memory that should be used to emulate portable computer RAM. However, there is no corresponding ROMSIZ parameter because the simulator automatically allocates enough PC memory for the ROM image. The RAMFILL parameter specifies a hexadecimal byte value with which to initially fill the area of PC memory that is used to emulate portable computer RAM. The SAVE parameter specifies the name of a RAM image file to either load when starting or produce when terminating if <ALT-F10> was pressed. The simulation can be terminated by pressing either <ALT-F9> or <ALT- F10>. <ALT-F10> has the added effect of saving the RAM image if a SAVE parameter was specified in the parameter file. When running the simulation, the PC's peripherals are accessed as if they were connected to a portable, except for hard disks, printers and asynchronous serial communication hardware. The simulator only supports floppy disks and docs not provide support for printers and communications.